home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
BBS Toolkit
/
BBS Toolkit.iso
/
doors_1
/
gapqbdr.zip
/
GAPQBDR.TXT
< prev
next >
Wrap
Text File
|
1990-07-09
|
123KB
|
3,075 lines
GAPQBDR
Door Interface Module - October 1, 1989
A Professional Development Kit For The Professional Programmer
(C) Copyright 1988, 1989 The GAP Development Company
ALL RIGHTS RESERVED
TABLE OF CONTENTS
Page
DESCRIPTION 2
GETTING STARTED 3
COMPILING AND LINKING 8
SYSOP SETUP AND FUNCTIONS 9
GLOBAL VARIABLES 12
CONSTANTS 12
ANSI CONSTANTS 12
DOOR.SYS VARIABLES 13
INTEGERS 13
LONGS 13
STRINGS 13
GAPQBDR GLOBALS 14
INTEGERS 14
LONGS 14
STRINGS 14
GAPDOS.DAT VARIABLES 14
USERS.DAT VARIABLES 15
PCBOARD.SYS VARIABLES 16
PCB USERS VARIABLES 16
GLOBAL VARIABLES - ALPHABETICALLY By Type 18
CONSTANTS 18
INTEGERS 18
LONGS 19
STRINGS 19
FUNCTIONS AND SUBROUTINES - QUICK REFERENCE 22
FUNCTIONS AND SUBROUTINES - REFERENCE 23
GAPQBDR LICENSE AGREEMENT 43
REGISTRATION INFORMATION 44
GAPQBDR REGISTRATION 45
INDEX 46
DESCRIPTION
-----------
GAPQBDR is a professional development kit for Bulletin Board Door
programmers. It can also be used to facilitate the writing of
stand alone communications programs. Written entirely in Quick
Basic (with a little help from some Assembler support routines),
it is fast, reliable, easy to use, and easy to incorporate into
the serious programmer's source code.
Features Include :
o Interfaces with GAP Communications and pcboard.
o Complete interrupt driven communications which does not
require a DTR patched BRUNxx.EXE run time library.
o Supports the FIFO buffers of the 16550 UART.
o Speeds to 38.4k baud.
o Supports all communications ports.
o Supports CTS checking, even at 300 bps, for error free
transmissions.
o Does not require watchdog or CTTY.
o Uses ANSI colors instead of Basic's color statements so the
sysop sees what the caller sees.
o Maintains a scoreboard of the top 10 players.
o High speed text file display.
o Supports ANSI color and ASCII text files with no programming
effort other than to make a single subroutine call.
o Easy to use Random Number Generator.
o Informative Status Line display.
o Monitors keyboard activity and caller time remaining.
o Easy interfacing to BBS system and user files.
o Sysop chat with full word wrapping.
o Allows the sysop to shell to DOS.
o "Remembers" the default drive and directory which prevents
file access errors.
o Credits caller with time spent chatting or while sysop is in
a DOS shell.
o Sysop can twit caller without caller ever knowing the sysop
is watching.
o Caller time can be increased or decreased.
o Full programmer control of whether or not to update the BBS
system files.
o Time calculations are not dependent on the "seconds since
midnight" and are thus unsusceptible to the midnight roll
over.
o Timer routines are hardware independent.
o Allows the sysop to override the "more" prompt during file
shows.
o Allows the sysop to "force" a file display.
o Automatic detection of multi-user system.
o Input routines are consistent throughout the program.
o Uses the latest in Quick Basic features.
o Extremely easy interfacing to door programs.
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
GETTING STARTED
---------------
GAPQBDR is distributed in archived format. The contents of the
archive should be as follows:
GAPQBDR.TXT - This documentation.
GAPQBDR.QLB - Library routines for QB environment.
GAPQBDR.LIB - Standard Library routines for BC.
GAPQBDR.BI - Door Interface include file.
DOOR.ZIP - Sample program illustrating many of
the features of GAPQBDR.
READ.ME - Any pertinent information which you
should read.
If you licensed the source code to GAPQBDR, the following files
are included in an archive called GAPQBSRC:
ACCESS.BAS - Basic source for file access.
CARRIER.BAS - Basic source for no carrier routines.
DOCHAT.BAS - Basic source for sysop chat.
GAPDOS.BAS - Basic source to read/write GAPDOS.DAT.
GAPQBDR.BAS - Basic source for main GAPQBDR functions.
GAPUSER.BAS - Basic source to read/write GAP USERS.
GETRAND.BAS - Basic source for random number routines.
INITDOOR.BAS - Basic source for door initialization.
LEAVE.BAS - Basic source for closing the door.
PCBSYS.BAS - Basic source to read/write PCBOARD.SYS.
PCBUSER.BAS - Basic source to read/write PCB USERS.
PUTCHAR.BAS - Basic source for character output.
SCOREBRD.BAS - Basic source for scoreboard routines.
SHOWFILE.BAS - Basic source for file display.
STATUS.BAS - Basic source for the status line.
SYSPAGE.BAS - Basic source for page sysop routines.
TIMCRED.BAS - Basic source for time credits.
WAIT.BAS - Basic source for time pauses.
ATSAY.ASM - Assembler source for screen positioning.
CLS.ASM - Assembler source for clear screen.
CTRLC.ASM - Assembler source for CTRL-C handler.
CURSOR.ASM - Assembler code for cursor positioning.
DOSPRINT.ASM - Assembler source for BIOS string output.
GAPPUTS.ASM - Assembler source for string output.
GETKEYC.ASM - Assembler source for keyboard input.
KEYBRD.ASM - Assembler source for keyboard function.
GAPQBSRC.BI - Global declarations for source files.
MAKELIBS.BAT - Batch file for compiling the source
modules and creating libraries.
LIBLIB - LIB response file.
QLBQLB - Linker response file.
SRCREAD.ME - Any pertinent information which you
should read.
Page 3
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
In addition, all the object modules for the private GAPQBDR
functions are provided so that you may create the quick library.
You will also need the file QB.BI which is distributed with the
Microsoft QB disks. A DTR patched BRUN45.EXE is not needed since
GAPQBDR uses its own communications routines.
Place the files in your QB work directory. Make sure that QB.BI
is accessible to the compiler. The source files should be placed
in a directory called SOURCE (off of your QB directory).
Throughout this document, the terms function, routine, procedure
and subroutine are used interchangeably. However, pay close
attention to the return value and the examples. In QB, a
function returns a value, where as a sub program does not.
If you use an external editor to write your programs, the editor
must allow control characters to be entered and displayed. The
ANSI constants are initialized by literal characters and if your
editor removes the ESC character from the constants, your ANSI
displays will be quite messy.
If you are using the QB environment, you will need to load the
door module along with your source program. To do so, type the
following :
QB door /L GAPQBDR
(where door is the name of your basic source program)
If you fail to load the quick library along with your program,
you will receive a great many "subprogram not defined" errors
when you try to compile or run your program.
We are a firm supporter of declaring all variables prior to their
use. Not only does it make your programs easier to debug, it
makes them easier to read and follow. We recommend that you
follow our guidelines and declare all of your global variables at
the beginning of your program, after including GAPQBDR.BI.
At the very beginning of your program, you must include the
GAPQBDR.BI file. Without this file, nothing will work. It must
be the first directive in your source file. To include the file,
you type the following at the beginning of your source program:
'$INCLUDE: 'GAPQBDR.BI'
Do not under any circumstances use the DEF type statements (I.E.,
DEFINT A-Z). This is the lazy persons method of programming.
Typedef your variables by either declaring them ahead of time, or
by appending the type after the name (i.e., A$, I%).
If you need to use your own On Error routines, you should modify
the supplied error handler rather than simply ignore it or
Page 4
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
replace it. If you subsequently change the Error Trap address, it
is your responsibility to deal with any run time errors.
After declaring any variables and functions, you must include the
error handling file. The error handler is included in your source
module so that it can be globally accessible by all routines in
the GAPQBDR library. To include the file, type the following
immediately AFTER declaring your global variables and BEFORE any
executable statements:
'$INCLUDE: 'GAPQBERR.BI'
It is important that the error handling file be inserted at the
proper place in your program. The file may not be included before
your variable declarations and it MUST be included prior to your
first executable statement. Please see the example program for a
sample of how to include this file. Remember that a variable
assignment is not a variable declaration but an actual executable
statement.
You are now ready to begin your program. You may now initialize
your variables and start your program.
The first thing that must be done prior to using any of the door
functions, is to initialize GAPQBDR itself. This is done by
making a call to read.cnf. Read.cnf opens the configuration file
(the name of which you pass as a parameter) and reads the first
three lines of the file. If the configuration file cannot be
found, the program will end. The format of the configuration
file is as follows:
-----------------------------------------
c:\gap
The Crow's Nest
0
The first line of the file is the path to the BBS default
directory. The second line is the name of the BBS. The third
line is a flag that tells GAPQBDR if the host BBS system is GAP
or PCB. For GAP, set this line to 0. For PCB, set it to 1. The
configuration file is usually given a name similar to the name of
your door program, with a CNF extension. Read.cnf will leave
this file open for your use. If you have any configuration
options of your own, you may place them in this file beginning
with line 4. Do not read your configuration options until after
making a call to init.door (which should be the second function
call in your program). Upon return from init.door, you are free
to read your configuration options (if any). At this time, you
should close the configuration file. Its file number is #1.
Normally, your program is invoked with a command line parameter
giving the name of the configuration file to use:
(I.E., DOOR DOOR.CNF).
Page 5
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
You would use the COMMAND$ function to extract the configuration
parameter and then pass this parameter on to read.cnf. This
allows the end user to use a single program (your program) with
multiple configuration files. This is especially important under
multi-user systems where separate configuration files are needed.
The configuration file is opened as a sequential file so using
Line Input #1 would be appropriate for reading any data.
If there were no errors, read.cnf will return. You must now make
a call to init.door. Init.door uses the information derived from
line 1 of the configuration file to open and read DOOR.SYS (GAP)
or PCBOARD.SYS (PCB) as well as the BBS configuration file. In
addition, init.door opens the communications port (if a remote
user is on), initializes some global variables, initializes the
random number generator, and installs the CTRL-C interrupt
handler. If there is an error, init.door will not return.
Instead it will end the program.
That is basically all you have to do to initialize the GAPQBDR
module. When your program ends, you should clean house if
necessary and call leave. Leave closes the communications port
and any open files, sends a sign off message to the caller, and
then exits to DOS.
Things to remember:
To get the ball rolling, include GAPQBDR.BI as the first
directive in your source program.
Include GAPQBERR.BI after declaring any global variables and
prior to your first executable statement.
To initialize the door, call read.cnf with the name of your
programs configuration file. Call init.door.
Call leave when your program is finished.
With the exception of file #1 which is used to read the
configuration file and which YOU should close, there are no
other files left open. GAPQBDR uses good programming practice
by asking Basic for a file number rather than telling Basic
which number to use.
All input and output should be performed through the GAPQBDR
functions. The sample program gives good examples on how to
accomplish this.
To determine if the BBS is a single or multi user system, check
the variable called node. If it is anything other than 0, then
the BBS is multi-user and you should read/write your data files
with sharing attributes.
Page 6
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
The default mode of operation is GAP mode. This means that you
should not use those functions which access PCB files. To
determine if the BBS is a PCB system, check the variable
do.pcb. If this is set to 1, then the BBS is PCB and you should
not access GAP files. The variable do.pcb is set to 1 if line
3 of the door configuration file is set to 1.
To test your program, you will need a DOOR.SYS (GAP) or a
PCBOARD.SYS (PCB) file that was written for local exit. Of
course, you can always modify any DOOR.SYS file and change the
first line so that it reads COM0:. In addition, for a GAP BBS,
the GAPBBS.CNF file must be accessible (PCBOARD.DAT and
USERS for PCB). A complete set of sample files are provided for
testing your program under local mode. Experience has shown that
although the QB environment editor makes for a cumbersome
programmers editor, testing programs inside QB is perhaps the
easiest and most efficient way to test. The environment is
wonderful for catching syntax errors and even more fantastic at
allowing the programmer to correct those errors and continue to
run the program.
Do not use any of the Basic input/output or screen positioning
functions. If you do, you will find that if you attempt to
"print" a string, the string will not appear on the screen where
you might think it should. This is because Basic maintains its
own cursor location, and GAPQBDR does NOT update this
information. All input/output should take place using the
functions provided by GAPQBDR. Not only are they more efficient
than Basics, they are faster as well!
Page 7
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
COMPILING AND LINKING
---------------------
GAPQBDR has already been compiled with the necessary compile time
switches.
To compile your programs, use whatever switches are required by
your program along with the /x (on error) switch which is needed
for the error handling routine. Use the following commands:
bc /x doorname;
link doorname,,NUL.MAP,+gapqbdr
Where doorname is the name of your program.
WARNING: Do NOT, under any circumstance, use the /mbf compile
time switch. GAPQBDR expects all of its numeric
variables to be in IEEE format. If you have a need to
manipulate a PCB data file (which contains MBF format
numbers), declare the MBF fields as strings and use
either CVSMBF or CVDMBF to convert the strings. You will
see an example of this in the record structure for the
PCB USERS file. The fields downbytes and upbytes are
actually DOUBLES. The field lastmsg is actually a
SINGLE. To convert downbytes you can use : downbytes =
CVDMBF(pcbuser.downbytes). If you update this field in
the PCB USERS file, you can save it by using :
pcbuser.downbytes = MKDMBF$(downbytes).
The Microsoft Binary format for numbers should never be
used. Support for the MBF format will no doubt disappear
in future versions of QB. You should ALWAYS use the
latest versions and features of your compiler.
IEEE Format numbers provide for greater accuracy and
wider ranges. They are compatible with assembler and C.
They also allow you to use a math coprocessor, if one is
available.
You should also use LONG INTEGERS instead of SINGLE or
DOUBLE precision numbers where appropriate. A long
integer can represent a number as great as 2.1 billion!
This should more than cover your needs. Especially
since a BBS (door) program rarely uses or has a need for
real numbers.
If you are converting an old door program that uses MBF
format numbers in random access files, you will need to
use either the QB supplied conversion functions or
convert your random access data files to the new user
defined binary type record structures.
Page 8
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
SYSOP SETUP AND FUNCTIONS
-------------------------
These sysop setup and function descriptions should be placed in
the documentation of your door program. You should, of course
change the setup information to fit your particular needs.
Door programs written with the GAPQBDR Door Interface Module will
run on GAP Communications version 4 and greater and on PCB
version 14 and greater.
To configure the door for a particular BBS setup, a configuration
file must be used. At the very minimum, this file will contain
three lines. It may contain more than three, depending upon a
particular doors configuration requirements. The name of the
file is usually the same as that of the door program but with a
CNF extension. The minimum requirements for the file are as
follows:
c:\gap
The Crow's Nest
0
The first line is the full path to your BBS default
directory. For GAP, this is usually C:\GAP. For PCB, this
is usually C:\PCB. The second line is the name of your BBS.
The third line is a flag that tells GAPQBDR what BBS system
it is running under. A 0 means GAP, and a 1 means PCB.
GAPQBDR will obtain the sysop's name from the BBS configuration
file.
You must now create a batch file to invoke the door. This batch
file is placed in your BBS default directory. Such a batch file
might look like this:
echo off
cd \gap\doors\tl
tl tl.cfg
cd \gap
gap
As you can see, the door is invoked by passing the configuration
file name as a parameter.
Page 9
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
You will also need to modify your doors menu files and the data
file that tells the BBS what your doors are and the security
level needed to access them. For GAP, these are respectively:
DOORM
DOORMG
DOORS.DAT
Please refer to your BBS documentation for details on setting
these files up.
If you are running multi-nodes, simply create a separate door
configuration file for each node, and number them. For instance,
for a 3 node system, you might have the following configuration
files:
TL1.CFG
TL2.CFG
TL3.CFG
The only difference between the three would be the 1st line which
points to the default directory for the particular node.
Multi-user operation is automatic. For GAP, the presence of
DUMMYLOK.DAT in the MAIN directory triggers multi-user operation.
For PCB, this information is derived from the PCBOARD.DAT file.
The following files are read during door initialization. They
must be present or the door will not operate.
GAP PCB
---------------- ----------------
DOOR.SYS PCBOARD.SYS
GAPBBS.CNF PCBOARD.DAT
USERS
In addition, a particular door may access the GAP USERS.DAT and
GAPDOS.DAT files.
The following sysop functions are available while awaiting
keyboard input :
F5 - Shell to DOS.
F8 - Twit user and return to BBS.
F10 - Initiate chat with user.
CF10 - Answer user page bell.
Home - Main user stats.
End - Displays sysop keys available.
PgDn - Secondary user stats.
Up Arrow - Increase user's time remaining.
Dn Arrow - Decrease user's time remaining.
Page 10
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
One of the nicer features about using the TWIT key, is the user
is not told that "the sysop wants them to return to the BBS".
Instead, a very plain and simple message of "returning you to the
BBS" is displayed. This way, the user is given no indication
that the sysop is hovering about.
When using the F5 shell to DOS key, to return to the door
program, simply type EXIT at the DOS command prompt. It is not
necessary to change directories back to the door directory.
GAPQBDR is smart enough to know which drive and directory the
door program is in and will reset the defaults upon return from
DOS.
The Up and Down Arrow keys increase and decrease the user's time
respectively by 5 minutes for each press of the key. There is no
indication of what is occurring (except by the fact the user's
time remaining will change), so the sysop should try not to have
a lead finger. The increase or decrease is effective only while
the user is in the door. Since we are firm believers that the
BBS system files belong to the BBS and should not be altered by
any door program, updating the BBS system file is NOT automatic.
If you wish that any decrease or increase in the user's time be
made permanent, you may, after initializing the door, call the
function that opens the system file. Keep track of any time
credits during the door programs operation, then call the
function that updates the BBS system file. Examples of how to do
this are included in the sample program.
Page 11
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
GLOBAL VARIABLES
----------------
All global variables (except for constants) are defined as COMMON
SHARED. They are included in your program by including the file
GAPQBDR.BI at the top of your source file.
CONSTANTS
---------
Constants are defined as - CONST name = constant value.
NO Defined as 0
YES Defined as 1
ANSI CONSTANTS
--------------
ANSI constants contain the actual ANSI color sequences.
BLACK ANSI codes for Black
BLUE ANSI codes for Blue
BROWN ANSI codes for Brown
CYAN ANSI codes for Cyan
GREEN ANSI codes for Green
MAGENTA ANSI codes for Magenta
RED ANSI codes for Red
WHITE ANSI codes for White
BBLACK ANSI codes for Grey
BBLUE ANSI codes for bright Blue
BCYAN ANSI codes for bright Cyan
BGREEN ANSI codes for bright Green
BMAGENTA ANSI codes for bright Magenta
BRED ANSI codes for bright Red
BWHITE ANSI codes for bright White
YELLOW ANSI codes for Yellow
Page 12
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
DOOR.SYS VARIABLES
------------------
DOOR.SYS variables are initialized while reading the Door
Interface Module, DOOR.SYS. (For PCB, PCBOARD.DAT and USERS must
be read to initialize these variables). These variables are
available from door start up to door end. The DOOR.SYS variables
are the door programmer's connection to the BBS.
INTEGERS
--------
alarm Caller Alarm. 0 = off, 1 = on
bell Page Bell. 0 = off, 1 = on
c.olor Color toggle. 0 = no color, 1 = color ok
expert Expert mode. 0 = non-expert, 1 = expert
l.ocal 0 = remote user, 1 = local
level User's security level
minsleft Number of minutes user has left at door start
node Node number. 0 = single user
page User's page length
parity Should actually be data bits and is not used
port Communications port in use
printer Printer Toggle. 0 = off, 1 = on
s.creen Screen display. 0 = off, 1 = on
LONGS
-----
baud DTE rate to open COMM port at
downbytes Total bytes downloaded
downloads Number of downloads
maxbytes Maximum number of bytes allowed to download
recnum User's record number in USER file
timeson Number of times user has been on
upbytes Total bytes uploaded
uploads Number of uploads
userbaud BPS rate of the remote user
STRINGS
-------
bphone User's business or data phone number
city User's home town
first User's first name
hphone User's home phone number
last User's last name
lastdate Last date user was on
password User's password. PASSWORD if sysop is on
subscrip Date user's subscription expires
username User's full name
Page 13
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
GAPQBDR GLOBALS
--------------
These variables are the documented, global variables (initialized
and used by GAPQBDR). They may be modified and/or used at the
programmer's discretion.
INTEGERS
---------
do.pcb If set to 1, the BBS is a PCB system
noup If set to 1, get.string will not uppercase
timecredit Time credits for user (in minutes)
timeleft Time user has left (in minutes)
LONGS
-----
starttime Time the user logged on (in seconds)
temptime For calculating keyboard time out
timenow Time it is now (in seconds)
STRINGS
-------
anystring1 Global garbage collector
bbs.dir Path to BBS default dir
birthday Callers birth date
board.name Name of the BBS
gendir Path to the gen directory
maindir Path to the main directory
sysname Sysop's name
GAPDOS.DAT VARIABLES
--------------------
These variables are initialized by the programmer by making a
call to read.gapdos. Note that string variables are fixed length
and will contain a NULL byte. Please see the GAPQBDR.BI include
file for the actual definition of these variables.
gapdos.baud DTE bps rate
gapdos.callbytes Ttl bytes available for download
gapdos.didnew 1 = did a new files scan
gapdos.exitdos 1 = exit to DOS after call
gapdos.forumnum Forum the user is in
gapdos.givetime 1 = event pending, else extra time received
gapdos.joined Bit flags of forums joined
gapdos.localc 0 = user, 1 = sysop, 2 = local user
gapdos.minavail Total minutes available to user
gapdos.port Port being used
Page 14
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
gapdos.starttime Time (in seconds) user logged on
gapdos.timecredit Any time credits user may have
gapdos.userbaud User's bps rate
gapdos.userfirst User's first name
gapdos.userindex User's index into user file
gapdos.username User's full name
USERS.DAT VARIABLES
-------------------
These variables are initialized by the programmer by making a
call to read.gapuser. Note that string variables are fixed
length and will contain a NULL byte. Please see the GAPQBDR.BI
include file for the actual definition of these variables.
WARNING : STRING fields are fully padded with spaces and the last
position of the string is and MUST be a 0!
user.blts Total bulletins read
user.bphone User's work or data phone number
user.city City, state, and zip (padded)
user.curbytes Total bytes downloaded this call
user.curdown Total files dowloaded today
user.doors Total doors opened
user.downloads Total downloads
user.expert Novice = N, expert = Y
user.fname User's first name (padded)
user.handle User's handle (padded)
user.hphone User's home phone number
user.joined Total forums joined
user.lastdate Last date on - mm/dd/yy
user.lastdir Date last looked at a directory listing
user.lastfrm Last forum in
user.lastmsg Last message read
user.lasttime Last time on - hh:mm
user.level Security Level
user.lname User's last name (padded)
user.mesleft Total messages left
user.mesread Total messages read
user.minutes Total minutes last call
user.page Page length
user.passwd User's password (padded)
user.private Allow on private nodes?
user.protocol Transfer protocol (padded)
user.subscribe Date user's subscription expires
user.sysop Sysop record, 1 = Y, 0 = N
user.timeson Number of times on
user.ttlbytes Total bytes downloaded
user.ttlmins Total mins on
user.upbytes Total bytes uploaded
user.uploads Total uploads
Page 15
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
PCBOARD.SYS VARIABLES
--------------------
These variables are initialized automatically by init.door if the
BBS system is PCB.
pcbsys.baud Com port bps rate
pcbsys.calleralarm Caller alarm -1=on,0=off
pcbsys.colorc Color toggle Y,N,7
pcbsys.ctime Time user logged on as HH:MM
pcbsys.display Display on/off -1=on,0=off
pcbsys.eactive Event active -1=yes,0=no
pcbsys.errcorrect ECC modem -1=yes,0=no
pcbsys.event Event time as HH:MM
pcbsys.forumnum Forum user was in "0" = main
pcbsys.minsleft Minutes left for caller
pcbsys.node Node number as short integer
pcbsys.pagebell Page bell -1=on,0=off
pcbsys.password User's password
pcbsys.port Com port as "0","1", or "2"
pcbsys.printer Printer on/off -1=on,0=off
pcbsys.sevent Slide event -1=yes,0=no
pcbsys.sysopnext Sysop on next N,X,space
pcbsys.timeallowed Allowed time in minutes
pcbsys.timecredit Any time credits in minutes
pcbsys.timegiven Highest forum time given
pcbsys.timeon Time user logged on in minutes
pcbsys.timeused Time user has used that day
pcbsys.ttlbytes Total K bytes available
pcbsys.userbaud Caller bps rate (Local if local mode)
pcbsys.userfirst User's first name
pcbsys.username Name of caller
pcbsys.userrec User's record number
PCB USERS VARIABLES
-------------------
These variables are initialized automatically by init.door if the
BBS system is PCB. To utilize downbytes, upbytes, and lastmsg
you must use the QB Microsoft Binary Format conversion functions.
pcbuser.bphone User's work or data phone number
pcbuser.city City, state, and zip (padded)
pcbuser.cnfregis Forum registration
pcbuser.delete Delete, Y=yes,N=no
pcbuser.downbytes Total download bytes. Use CVDMBF
pcbuser.downloads Number of downloads
pcbuser.expert Expert mode Y=yes,N=no
pcbuser.hphone User's home phone
pcbuser.lastconf Last forum in
pcbuser.lastdate Last date user was on
Page 16
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
pcbuser.lastdir Last New files scan
pcbuser.lastime Last time user was on
pcbuser.lastmsg Last message read in main. Use CVSMBF
pcbuser.lastmsg1 Last message read in each forum
pcbuser.level User's level as short integer
pcbuser.name User's name
pcbuser.page Page length
pcbuser.passwd User's password
pcbuser.protocol Protocol type
pcbuser.regisdate Registration date
pcbuser.timeson Number of times on
pcbuser.upbytes Total upload bytes. Use CVDMBF
pcbuser.uploads Number of uploads
Page 17
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
GLOBAL VARIABLES - ALPHABETICALLY By Type
-----------------------------------------
CONSTANTS
---------
BBLACK ANSI codes for Grey
BBLUE ANSI codes for bright Blue
BCYAN ANSI codes for bright Cyan
BGREEN ANSI codes for bright Green
BLACK ANSI codes for Black
BLUE ANSI codes for Blue
BMAGENTA ANSI codes for bright Magenta
BRED ANSI codes for bright Red
BROWN ANSI codes for Brown
BWHITE ANSI codes for bright White
CYAN ANSI codes for Cyan
GREEN ANSI codes for Green
MAGENTA ANSI codes for Magenta
NO Defined as 0
RED ANSI codes for Red
WHITE ANSI codes for White
YELLOW ANSI codes for Yellow
YES Defined as 1
INTEGERS
--------
alarm Caller Alarm. 0 = off, 1 = on
bell Page Bell. 0 = off, 1 = on
c.olor Color toggle. 0 = no color, 1 = color ok
do.pcb 1 = This is a PCB system
expert Expert mode. 0 = non-expert, 1 = expert
gapdos.baud DTE bps rate
gapdos.forumnum Forum the user is in
gapdos.givetime 1 = event pending, else extra time received
gapdos.localc 0 = user, 1 = sysop, 2 = local user
gapdos.minavail Total minutes available to user
gapdos.port Port being used
gapdos.timecredit Any time credits user may have
gapdos.userbaud User's bps rate
l.ocal 0 = remote user, 1 = local
level User's security level
minsleft Number of minutes user has left at door start
node Node number. 0 = single user
noup 1 = get.string will not uppercase
page User's page length
parity Should actually be data bits and is not used
pcbsys.minsleft Minutes left for caller
pcbsys.timeallowed Allowed time in minutes
pcbsys.timecredit Any time credits in minutes
pcbsys.timegiven Highest forum time given
pcbsys.timeon Time user logged on in minutes
pcbsys.timeused Time user has used that day
Page 18
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
pcbsys.ttlbytes Total K bytes available
pcbsys.userrec User's record number
pcbuser.downbytes Total download bytes. Use CVDMBF
pcbuser.timeson Number of times on
pcbuser.uploads Number of uploads
port Communications port in use
printer Printer Toggle. 0 = off, 1 = on
s.creen Screen display. 0 = off, 1 = on
timecredit Time credits for user (in minutes)
timeleft Time user has left (in minutes)
user.curdown Total files dowloaded today
user.lastfrm Last forum in
user.level Security Level
user.minutes Total minutes last call
user.page Page length
LONGS
-----
baud DTE rate to open COMM port at
downbytes Total bytes downloaded
downloads Number of downloads
gapdos.callbytes Ttl bytes available for download
gapdos.joined Bit flags of forums joined
gapdos.starttime Time (in seconds) user logged on
maxbytes Maximum number of bytes allowed to download
recnum User's record number in USER file
starttime Time the user logged on (in seconds)
temptime For calculating keyboard time out
timenow Time it is now (in seconds)
timeson Number of times user has been on
upbytes Total bytes uploaded
uploads Number of uploads
userbaud BPS rate of the remote user
user.blts Total bulletins read
user.curbytes Total bytes downloaded this call
user.doors Total doors opened
user.downloads Total downloads
user.joined Total forums joined
user.lastmsg Last message read
user.mesleft Total messages left
user.mesread Total messages read
user.timeson Number of times on
user.ttlbytes Total bytes downloaded
user.ttlmins Total mins on
user.upbytes Total bytes uploaded
user.uploads Total uploads
STRINGS
-------
anystring1 garbage collector
bbs.dir Path to BBS default dir
birthday Callers birth date
Page 19
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
board.name Name of the BBS
bphone User's business or data phone number
city User's home town
first User's first name
gapdos.didnew 1 = did a new files scan
gapdos.exitdos 1 = exit to DOS after call
gapdos.userfirst User's first name
gapdos.userindex User's index into user file
gapdos.username User's full name
gendir Path to the gen directory
hphone User's home phone number
last User's last name
lastdate Last date user was on
maindir Path to the main directory
password User's password. PASSWORD if sysop is on
pcbsys.baud Com port bps rate
pcbsys.calleralarm Caller alarm -1=on,0=off
pcbsys.colorc Color toggle Y,N,7
pcbsys.ctime Time user logged on as HH:MM
pcbsys.display Display on/off -1=on,0=off
pcbsys.eactive Event active -1=yes,0=no
pcbsys.errcorrect ECC modem -1=yes,0=no
pcbsys.event Event time as HH:MM
pcbsys.forumnum Forum user was in "0" = main
pcbsys.node Node number as short integer
pcbsys.pagebell Page bell -1=on,0=off
pcbsys.password User's password
pcbsys.port Com port as "0","1", or "2"
pcbsys.printer Printer on/off -1=on,0=off
pcbsys.sevent Slide event -1=yes,0=no
pcbsys.sysopnext Sysop on next N,X,space
pcbsys.userbaud Caller bps rate (Local if local mode)
pcbsys.userfirst User's first name
pcbsys.username Name of caller
pcbuser.bphone User's work or data phone number
pcbuser.city City, state, and zip
pcbuser.cnfregis Forum registration
pcbuser.delete Delete, Y=yes,N=no
pcbuser.downloads Number of downloads
pcbuser.expert Expert mode Y=yes,N=no
pcbuser.hphone User's home phone
pcbuser.lastconf Last forum in
pcbuser.lastdate Last date user was on
pcbuser.lastdir Last New files scan
pcbuser.lastime Last time user was on
pcbuser.lastmsg Last message read in main. Use CVSMBF
pcbuser.lastmsg1 Last message read in each forum
pcbuser.level User's level as short integer
pcbuser.name User's name
pcbuser.page Page length
pcbuser.passwd User's password
pcbuser.protocol Protocol type
pcbuser.regisdate Registration date
pcbuser.upbytes Total upload bytes. Use CVDMBF
Page 20
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
subscrip Date user's subscription expires
sysname Sysop's name
user.bphone User's work or data phone number
user.city City, state, and zip (padded)
user.expert Novice = N, expert = Y
user.fname User's first name (padded)
user.handle User's handle (padded)
user.hphone User's home phone number
user.lastdate Last date on - mm/dd/yy
user.lastdir Date last looked at a directory listing
user.lasttime Last time on - hh:mm
user.lname User's last name (padded)
user.passwd User's password (padded)
user.private Allow on private nodes?
user.protocol Transfer protocol (padded)
user.subscribe Date user's subscription expires
user.sysop Sysop record, 1 = Y, 0 = N
username User's full name
Page 21
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
FUNCTIONS AND SUBROUTINES - QUICK REFERENCE
-------------------------------------------
a.ccess% Checks for the existence of a file.
ansi Displays ANSI escape sequences.
backspace Sends one or more backspaces.
ckeypress% Checks for a remote or local key press.
clear.scr Clears the local and remote screens
do.chat To allow sysop to chat with remote user.
elap.time Computes elapsed time.
get.string Gets a string of characters.
get.time& Returns number of seconds since 01/01/70.
getakey% Gets one key responses.
getrand% Returns a random number.
init.door Initializes the Door.
leave Shuts down door and returns to the BBS.
more Checks for a full screen.
nl Sends a CR/LF to local and remote.
no.carrier Prints a message if carrier lost.
pagesysop Alerts sysop that the user wants to chat.
pause Sends a "Press [Any Key] To Continue" prompt.
putachar Sends a single character.
putkey Used by chat for word wrapping.
read.cnf Reads the door configuration file.
read.doorsys% Reads DOOR.SYS.
read.gapdos% Reads GAPDOS.DAT.
read.gapuser% Reads USERS.DAT.
read.pcbsys% Reads PCBOARD.SYS.
read.pcbuser% Reads PCB USERS file.
read.score% Reads and displays the scoreboard.
right.trim$ Trims spaces from string.
set.status Displays status line.
show.file Displays text files.
show.mess Displays a message.
time.credit Gives credits for time used.
time.left Computes time remaining.
update.clock Updates status line clock.
waitasec Pauses for x number of seconds.
wrap.word Wraps a word.
write.gapdos% Writes GAPDOS.DAT.
write.gapuser% Writes USERS.DAT.
write.pcbsys% Writes PCBOARD.SYS.
write.pcbuser% Writes PCB USERS.
write.score Creates and maintains the scoreboard.
Page 22
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
FUNCTIONS AND SUBROUTINES - REFERENCE
-------------------------------------
Functions always return a value. The type of the return value is
denoted by the type modifier after a function name. The return
value should be assigned to a variable of the same type. For
instance, the function get.time& returns a long integer. To re-
trieve the return value, assign it to an long integer as :
long.int& = get.time&
Subroutines do not return a value. To call a subroutine, use the
Basic CALL function :
call get.string
Note that the functions contained in the assembler source modules
are documented in the printed manual. They are not described
here.
Name : a.ccess%
Purpose : Checks for the existence of a file.
Parameters : Full path and name of file
Return Value : 0 = file was found, 1 = file not found
Description : In order to avoid Basic errors that occur when
trying to open a file that does not exist, this
function should be used prior to opening any
file.
Example : r% = access%("GAPQBDR.DOC")
if r% <> 0 then
call show.mess("Can't Find GAPQBDR.DOC",NO,YES)
end if
Name : ansi
Purpose : Displays ANSI escape sequences
Parameters : ANSI color to display
Return Value : None
Description : This function will send a string of ANSI escape
sequences to the remote user and to the local
console. The ANSI codes for the various colors
are defined as constants in the GAPQBDR.BI file.
If the remote or local user is in non graphics
mode, the function returns immediately.
Example : call ansi(BWHITE)
Page 23
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
Name : backspace
Purpose : Sends one or more backspaces
Parameters : Number of backspaces to send
Return Value : None
Description : In order to actually erase a character on the
screen, you must send a 3 character sequence
which consists of backspace, space, backspace.
This function will send as many of these 3 char-
acter sequences as you specify in the parameter
list.
Example : call backspace(1)
str$ = "Press Any Key " ' set up string
call show.mess(str$,NO,NO) ' show string
c% = getkeyc% ' get a key
call backspace(len(str$)) ' erase string
Name : ckeypress%
Purpose : Checks for a remote or local key press
Parameters : None
Return Value : 0 = no key is waiting, 1 = a key is waiting
Description : This function will check the local keyboard as
well as the communications receive buffer to see
if a key is waiting to be read. It is most often
used in loops that need to receive a 1 character
keystroke.
Example : c% = ckeypress% ' key pressed?
c% = 0 ' initialize
do
| ' do something
|
c% = ckeypress% ' key pressed?
until c% <> 0 ' key pressed,exit
Name : clear.scr
Purpose : Clears local and remote screens.
Parameters : None
Return Value : None
Description : This routine will call CLS23 to clear the local
screen. If the remote caller is in non-color
mode, it sends a CHR$(12) to the remote screen,
otherwise it sends the ANSI clear screen
sequence.
Example : call clear.scr ' clear screen
Page 24
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
Name : do.chat
Purpose : To allow sysop to chat with remote user
Parameters : None
Return Value : None
Description : This function allows a one on one chat with a re-
mote user. If the caller is in graphics mode,
the sysop's key presses will be displayed in
green and the remote user's key presses will be
displayed in white. Text will automatically wrap
at column 76. To exit chat, press either the ESC
key or type a CTRL-X. Note that the user may
also send these characters to end chat. The user
will receive full credit for the time spent chat-
ting with the sysop. However, this function will
not update the BBS system file so it is possible
that the user may be logged off (with an out of
time message) when he/she returns to the BBS.
Example : call do.chat
response$ = " " ' initialize
call get.string(response$) ' get a string
if response$ = "P" then ' paging sysop
call do.chat ' chat with sysop
end if
Name : elap.time
Purpose : Computes elapsed time while waiting for keyboard
input
Parameters : None
Return Value : None
Description : This function is used in loops that await a key-
board response. Prior to entering the loop, the
variable called temptime should be initialized
with the current time. Once inside the loop, this
function should be called to keep track of the
elapsed time. If there is no keyboard response
within 4 minutes, the user will be logged off.
Example : call elap.time
temptime& = get.time& ' start timer
do
gc = getakey% ' get a key
if gc <> 0 then ' key pressed
exit do ' exit and process
end if
call elap.time ' activity?
loop ' continue
Page 25
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
Name : get.string
Purpose : Gets a string of characters
Parameters : String to fill
Return Value : None
Description : This is the main input routine. It will get a
string from either the remote user or the local
keyboard. The string passed will be set to the
characters received. The length of the input
string is determined by the length of the string
passed. Do not pass a fixed length string to this
routine.
Before calling, you must initialize the passed
string with spaces. The number of spaces in the
string determines the number of characters al-
lowed to be input. If a user attempts to type
more characters than allowed, the cursor will not
move pass the end of the string. Input ends when
the Enter key is pressed.
To initialize the string, use the Basic space$
function (IE, input$ = space$(10) - initializes
input$ to 10 spaces).
WARNING : It is extremely important that the
passed string be initialized. Failure to set the
string to spaces, will cause unpredictable
results!
This function does not return a new string con-
taining the keyboard input. Instead, it modifies
the string you pass to it in the parameter list.
The string will be stripped of any trailing
spaces.
get.string automatically uppercases the string.
If you wish to disable this feature, set the
variable noup to 1.
get.string will automatically check for keyboard
activity so it is not necessary for you to do so.
Example : instr$ = space$(10) ' initialize
call get.string(instr$) ' get string
Page 26
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
Name : get.time&
Purpose : Gets the number of seconds elapsed since 01/01/70
Parameters : None
Return Value : Number of seconds since 01/01/70
Description : This routine is equivalent to the C time() func-
tion. It is used throughout the GAPQBDR module to
compute various times. This function is not sus-
ceptible to the midnight roll over problem so
prevalent in Basic communications programs.
Note that the return value is of type LONG. You
must cast the return value to a LONG INTEGER or
loss of significant digits will result.
Example : dim ltime as long ' declare as long
ltime = get.time& ' get the time
' if you don't like declaring variables, you can
' do it the old fashioned way
longtime& = get.time& ' get the time
Name : getakey%
Purpose : Gets one key responses
Parameters : None
Return Value : ASCII code for the key pressed or 0
Description : This is the main keyboard input routine
(internal). It is called by get.string as well as
any keyboard polling loops. It checks the re-
ceive buffer as well as the local keyboard for a
key press. If one is not found it returns 0.
The character input is not echoed. Since 99% of
all keyboard input comes from this routine, it
checks for carrier, time remaining, keyboard
time-out, as well as special sysop function keys.
The "timeleft" variable is updated via this rou-
tine. This is the variable you would normally
use in a prompt such as,
[20 mins left] Main Command :
Example : c% = getakey
Page 27
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
Name : getrand%
Purpose : Gets a random number
Parameters : Low number, high number
Return Value : A random number
Description : This routine is provided because it is much
easier to use and understand than Basic's random
function. Provide as parameters two integers.
The first parameter is the lowest number you will
accept as a random number, and the second parame-
ter is the highest random number you will accept.
The function will return a random integer between
the range specified (low and high are included in
the range of numbers). It is not necessary to
seed the random number generator as this is done
automatically for you during program
initialization.
Example : rndnum% = getrand% (1,10) ' get a random
' number between 1
' and 10
Name : init.door
Purpose : Initializes the GAPQBDR functions
Parameters : None
Return Value : None
Description : This routine must be called immediately after
calling read.cnf. It initializes the door, opens
and reads system files, initializes the comm
port, initializes global variables and in gen-
eral, makes sure that all of the files required
for operation are present. There is no return
value. If an error occurs while trying to ini-
tialize, the function will display an error mes-
sage and end the program.
Example : call read.cnf("DOOR.CFG") ' read config file
call init.door ' init the door
Name : leave
Purpose : Exits the program
Parameters : None
Return Value : None
Description : When the program terminates, it must call this
function to end. This is the ONLY proper exit
from the door.
Example : call leave
Page 28
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
Name : more
Purpose : Checks for a full screen and issues a More Prompt
Parameters : None
Return Value : None
Description : This is an internal routine that is called by the
character output functions.
Example :
Name : nl
Purpose : To send a Carriage Return and Line Feed to local
and remote
Parameters : Number of New Line's to send
Return Value : None
Description : To send a blank line, call this routine with the
number of blank lines you wish to send.
Example : call nl(2) ' send two blank
' lines
Name : no.carrier
Purpose : Prints a message and calls leave()
Parameters : None
Return Value : None
Description : Internal routine that is called when there is a
loss of carrier. Displays a message to the local
screen and then calls leave to terminate the
program.
If you have a routine that checks for carrier and
you wish to display the standard "No Carrier"
message and log the user off, call this function.
Example : call no.carrier
Page 29
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
Name : pagesysop
Purpose : Alerts sysop that user wants to chat
Parameters : None
Return Value : None
Description : Allows the programer to provide the user with a
Page Sysop command. The page lasts for 30
seconds and can be aborted by typing CTRL K. If
the sysop's page bell is on, the sysop's speaker
will also sound. To answer the page, the sysop
should press CTRL F10.
Example : response$ = " " ' initialize var
call get.string(response$) ' wait for a key
if response$ = "P" then ' wants to chat
call pagesysop ' tell sysop
end if
Name : pause
Purpose : Sends a "Press [Any Key] To Continue" prompt
Parameters : None
Return Value : None
Description : This function sends a pause prompt and waits for
a key press.
Example : call nl(1) ' send blank line
call pause ' wait for a key
Name : putachar
Purpose : Send a single character to local and remote
Parameters : ASCII character to send
Return Value : None
Description : This routine is called a "semi-unfiltered" char-
acter output routine because it allows for most
ASCII characters to be output.
Example : c% = ASC("A") ' send an 'A'
call putachar(c%) ' to local and
' remote screen
c% = getakey% ' get a keypress
if (c% <> 0 then ' if we got a key
call putachar(c%) ' display the
end if ' character
Page 30
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
Name : putkey
Purpose : Used by chat routines to keep track of word
wrapping
Parameters : Character to send
Return Value : None
Description : This is the main output routine for the chat
functions. It keeps track of the current column,
and decides when it is time to wrap a word. It
should not be called by the programmer's routines
since putachar is faster and more efficient.
Example :
Name : read.cnf
Purpose : To read the door configuration file
Parameters : Full path and file name to the configuration
file.
Return Value : None
Description : Opens the configuration file for the current
door. Normally the passed parameter is the name
of the door with a .CNF extension (it is assumed
that the file is in the same directory as the
door program). If an error occurs, the program
ends immediately.
WARNING : The first three lines of this
configuration file belong to the GAPQBDR
interface module. You are free to use the
information, but the information contained in the
first three lines must conform exactly to the
following specifications.
The first line of this file is the full drive and
path to the BBS default directory. This is the
directory where the BBS system files can be found
(IE, GAPDOS.DAT, DOOR.SYS, GAPBBS.CNF). The en-
try on line 1 is not checked until init.door is
called.
The second line of this file is the name of the
BBS.
The third line is the BBS flag.
It is the responsibility of the door author to
describe the format of these three lines to the
end user. It is also the responsibility of the
door author to insure that the end user have
these three lines in the door configuration file.
If your door program requires no configuration
parameters of its own, you can simply distribute
Page 31
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
a sample "door".cnf file with these three lines
already in it.
GAPQBDR will NOT close this file (file #1) after
reading the first three lines. It leaves the
file open for the programmer's use. If your door
does require certain configuration parameters,
have your users place the parameters in the file
starting with line 4. If you use a set up pro-
gram, be sure that your set up program writes the
first three lines as specified.
After you have called read.cnf and init.door, if
you have any configuration options in the
"door".cnf file, you should line input those op-
tions. Then close file #1. Even if you have no
options to read, close the file.
WARNING : You MUST call this routine before using
any of the GAPQBDR functions. After calling this
routine, you MUST call init.door.
Example : call read.cnf("TOURIST.CNF")
call init.door
Page 32
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
Name : read.doorsys%
Purpose : Reads the DOOR.SYS universal door interface file
Parameters : None
Return Value : 0 = no error, 1 = error
Description : Internal routine called by init.door. Reads the
DOOR.SYS file and initializes any global vari-
ables that depend on the information in that
file.
Example : c% = read.doorsys%
Name : read.gapdos%
Purpose : Reads the GAP Communications DOS file.
Parameters : None
Return Value : 0 = no error, 1 = error
Description : Reads the GAPDOS.DAT remote exit to DOS file. If
you have a need for the information in this file,
or if you need to modify the record variables,
this function will read the file for you. The
record variables are contained in a variable
called gapdos.
WARNING : Do NOT modify the string fields in
GAPDOS.DAT. If the gapdos.userindex field is
changed, GAP will be unable to find the user in
the userfile upon return from the door.
The only proper way to update this file is to
first read it. Make any changes to the variables
themselves or use your own temporary variables.
Then call write.gapdos to update the record.
Example : c% = read.gapdos%
Name : read.gapuser%
Purpose : Reads the GAP Communications USERS.DAT file
Parameters : None
Return Value : 0 = no error, 1 = error
Description : Reads the user record of the current user in the
GAP USERS.DAT file. The record variables are
contained in a variable called user.
Example : c% = read.gapuser%
Page 33
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
Name : read.pcbsys%
Purpose : Reads the PCBOARD.SYS file.
Parameters : None
Return Value : 0 = no error, 1 = error
Description : For a PCB setup, this function is automatically
called by init.door. Do not use unless do.pcb is
set to 1.
Example : c% = read.pcbsys%
Name : read.pcbuser%
Purpose : Reads the PCB USERS file.
Parameters : None
Return Value : 0 = no error, 1 = error
Description : For a PCB setup, this function is automatically
called by init.door. Do not use unless do.pcb is
set to 1. Note that to change the fields
downbytes, upbytes, or lastmsg, you will need to
use the QB functions CVSMBF or CVDMBF.
Example : c% = read.pcbuser%
Name : read.score%
Purpose : Reads and displays the top 10 player file.
Parameters : Filename to read, message to display.
Return Value : 0 = ok, 1 = file not found
Description : This function reads the scoreboard file and
displays it to the caller. Pass as the first
parameter, the name of the scoreboard file. The
second parameter is a string to display prior to
showing the actual scores.
Example : c% = read.score% ("SCORE.DAT","Top 10 Players")
if c% = 1 then
call show_mess("No winners yet!",NO,YES)
end if
Name : right.trim$
Purpose : Trims spaces from the end of NULL terminated
strings
Parameters : String containing the spaces.
Return Value : String without the spaces.
Description : This function will remove the NULL and trim any
spaces from the right end of any 'C' string.
Example : username$ = right.trim$(gapdos.username)
Page 34
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
Name : set.status
Purpose : To display and update the sysop status line
Parameters : 0 = set the status line, 1 = update the status
line, 4 = show other user stats
Return Value : None
Description : This routine is used internally. There should be
no reason to call it unless you have modified a
user's stats and you need to update those stats
on the status line. In this case, you should use
option 0.
Example : call set.status(0)
Name : show.file
Purpose : To display a text file
Parameters : The full path and file name to the file to be
shown
Return Value : None
Description : Many door programs have welcome, news, exit, help
and other files to show to the user at various
points in the program. This is the function that
allows you to do that. This function tries to be
as intelligent as it possibly can in determining
the sysop's wishes. To display a file to the
user, call the function with the full
drive\path\filename of the file to display.
If you have color and non-color versions of files
pass the name of the non-color version as this
function will automatically append a "G" to the
filename if the user is in color mode. In fact,
this function will ALWAYS try to find a file with
a "G" appended to the end of the name (if the
user is in color mode) before it looks for the
actual file by the name you specified. If you
pass "WELCOMEG" to this function and the user is
in color mode, it will first try to find a file
with the name of "WELCOMEGG".
As with GAP Communications, your text files can
have certain control characters as the first
character in the file. A "{" signals that the
more prompt should never display. In other
words, GAPQBDR will not keep track of the number
of lines displayed and will never issue a more
prompt. This is useful for very long ANSI files.
A "@" signals that the pause prompt should be
displayed when the screen is full instead of a
more prompt. This is very handy when you want
the user to see the file in its entirety. The
user will not be allowed to break out of the file
Page 35
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
read.
WARNING : The "{" or "@" MUST appear as the VERY
first character in the file. If you use an ANSI
editor, be aware that the first few characters in
a file will usually be an ANSI color sequence.
You normally have to edit the file with a text
editor to insert the control character.
Because QB 4.x is EXTREMELY slow when it comes to
function calls, all input and output is done "in
line". Despite QB's high overhead, this function
is pretty fast.
GAPQBDR does not have GAP's ability to protect
the status line. Because of this, it is possible
for an ANSI file that contains clear screen codes
to erase the status line. At the end of the
function, the status line will be re-drawn just
in case. Since most ANSI files contain the clear
screen codes at the beginning of the file,
show.file will remove any such codes during the
first read of the file.
Pressing CTRL K or CTRL X will abort any file
display if the file does not begin with a "@".
REMEMBER : If you have both color and non-color
versions of the same files, pass the name of the
non-color version. Also, the actual disk files
must be named in such a way that they have no
file extension and the color version ends with a
"G".
Example : call show.file("WELCOME")
call show.file("C:\GAP\GEN\WELCOME")
Page 36
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
Name : show.mess
Purpose : Displays a message
Parameters : Message, ring the bell, issue a New Line
Return Value : None
Description : Finally! After all of this, just how do you dis-
play a message to the user? Well, here it is.
This is the string output function for GAPQBDR.
Under most circumstances, this is the one func-
tion that you would call to display output to the
user. There should be no reason to ever call
putkey or putachar, as they are basically inter-
nal routines.
There should be no reason to EVER use the Basic
print statement unless you need to display a mes-
sage to the local screen that you do not want the
remote user to see. In other words, ALL string
output should be done through this function. If
there is a reason to display information locally
it would be much easier and more efficient to
keep track of the l.ocal variable, set it to 1,
call show.mess with the strings to be displayed,
then restore the l.ocal variable to what it was
before, instead of using the print function which
cannot display ANSI sequences (forcing you to
translate ANSI codes to color statements).
The three parameters are :
1 - the string to display
2 - YES or NO if you want to sound the remote
user's bell.
3 - YES or NO if you want to issue a CR/LF
after displaying the string.
Page 37
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
Example : ' the first show.mess displays the string and
' leaves the cursor on the same line. The second
' show.mess displays the string, rings the remote
' user's bell, and drops the cursor to the next
' line.
call nl(1)
call show.mess("Are you ready? (Y/N) : ",NO,NO)
a$ = space$(3)
call get.string(a$)
if left$(a$,1) = "Y" then
' begin whatever it is you want to begin
else
call nl(1)
call show.mess("Too Bad!",YES,YES)
end
end if
Name : time.credit
Purpose : Keeps track of time and credits the user with
time elapsed
Parameters : 1 = start timer, 0 = end timer
Return Value : None
Description : This is basically an internal routine called by
chat and sysop shell to DOS so that the user is
not penalized for time used. It updates a global
variable called timecredit. Timecredit is used
in the calculations that determine the user's
time remaining.
If you wish to use this feature in your own rou-
tines, prior to entering your routine, call
time.credit with a 1 and it will start the timer.
When your routine is finished, call time.credit
with a 0 and the timer will stop. The variable
timecredit will be updated with the elapsed time.
Example : call time.credit(1) ' start the timer
call do.chat ' chat with user
call time.credit(0) ' stop the timer
' Note that this is simply an example. do.chat
' calls time.credit on its own. In the above
' example, if the sysop chat with the user took
' 10 minutes, the user will be credited with
' that 10 minutes as will be reflected in the
' timecredit variable.
Page 38
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
Name : time.left
Purpose : To compute the user's time remaining
Parameters : None
Return Value : None
Description : This is the routine that is called by the input
and output routines to compute the user's time
remaining. It is not necessary for the programmer
to call this routine directly.
A global variable called .i.timeleft; will be
updated with each call. This variable may be
used in prompts that display the user's remaining
time.
As long as all input/output is performed thru
calls to the GAPQBDR library, the timeleft vari-
able will always be current.
Example : call time.left
Name : update.clock
Purpose : Updates the status line clock
Parameters : None
Return Value : None
Description : Internal routine to update the status line clock.
Example :
Name : waitasec
Purpose : Pauses for the number of seconds specified.
Parameters : Number of seconds to pause
Return Value : None
Description : This function allows you to pause all processing
for the specified number of seconds. It is in-
sensitive to processor speed and is immune to the
midnight rollover problem.
Example : call waitasec(10) ' pause for 10 sec
Name : wrap.word
Purpose : To wrap a word during sysop chats
Parameters : None
Return Value : None
Description : Internal function called by putkey to wrap words.
Example :
Page 39
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
Name : write.gapdos%
Purpose : Updates the GAPDOS.DAT file
Parameters : None
Return Value : 0 = no error, 1 = error
Description : This function allows the programmer to update the
GAP Communications remote exit to DOS system
file. If the GAPDOS.DAT file is read at door be-
ginning, the timecredit variable assigned to
gapdos.timecredit, and the GAPDOS.DAT file writ-
ten out at doors end, the user will be credited
with any time spent during a sysop chat or shell
to DOS.
Example : c% = read.gapdos% ' read the file
if c% = 0 then ' if no error...
timecredit = gapdos.timecredit
' do some processing
' give the user 20 more minutes
timecredit = timecredit + 20
gapdos.timecredit = timecredit
c% = write.gapdos% ' update the file
end if
Page 40
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
Name : write.gapuser%
Purpose : Updates the user record in GAP's USERS.DAT file
Parameters : None
Return Value : 0 = no error, 1 = error
Description : This function allows you to update any variables
in the GAP USERS.DAT file for the current user.
WARNING : The GAP USERS.DAT file contains C char-
acter arrays. These are equivalent to Basic's
fixed length strings with the exception that the
C strings have a NULL character (chr$(0)) in the
last position. If you modify any of these fixed
length strings, you MUST make sure that the
string is fully padded with spaces and that the
NULL character is placed in the last string posi-
tion. When assigning a value to a fixed length
string, Basic will automatically pad the fixed
length string with spaces. All the programmer
need to is insure that the NULL is inserted at
the end of the string.
WARNING : The index for the user file consists of
the user's last name and first name. Do not un-
der any circumstances modify either of these two
fields. Doing so will cause corruption of the
Index file.
Example : ' give the user a level of 50
c% = read.gapuser% ' 1st read record
user.level = 50
c% = write.gapuser% ' update the rec
' allow user to change handle
c% = read.gapuser%
if c% = 0 then
call show.mess("Enter New Handle : ",NO,NO)
handle$ = space$(15)
call get.string(handle$)
if handle$ <> "" then
user.handle = handle$
mid$(user.handle,16,1) = chr$(0)
c% = write.gapuser%
if c% = 0 then
show.mess("Saved new Handle",NO,YES)
end if
end if
end if
Page 41
GAPQBDR (C) Copyright 1988,1989 The GAP Development Company
Name : write.pcbsys%
Purpose : Updates the PCBOARD.SYS file
Parameters : None
Return Value : 0 = no error, 1 = error
Description : This function allows the programmer to update the
PCBOARD.SYS File. Do not use unless do.pcb is
set to 1.
Example : c% = write.pcbsys% ' write the file
Name : write.pcbuser%
Purpose : Updates the PCB USERS file
Parameters : None
Return Value : 0 = no error, 1 = error
Description : This function allows the programmer to update the
PCB USERS File. Do not use unless do.pcb is set
to 1. Note that you will need to use MKSMBF on
the field lastmsg, and MKDMBF on the fields
downbytes and upbytes, if you modified these
fields since reading the file.
Example : c% = write.pcbuser% ' write the file
Name : write.score
Purpose : Creates and maintains the scoreboard file.
Parameters : Filename to write, score to write.
Return Value : None
Description : This function will create and maintain a data
file of the top 10 scores. You pass as
parameters, the name of the file to use as the
scoreboard file, and the score to write. The
score is a long integer. The name and date are
already known. If the file does not exist, it
will be created.
Example : DIM score AS LONG
score = 45600
write.score("SCORE.DAT",score)
Page 42
GAPQBDR LICENSE AGREEMENT
-------------------------
This legal document is an agree- GAP Development Company consents
ment between you, the end user, in writing, in advance.
and GAP Development Company. By
using the GAPQBDR software Registration of the SOFTWARE is
(the "SOFTWARE") provided by GAP REQUIRED as a condition of use.
Development Company, you agree
to become bound by the terms of You are granted a royalty-free
this agreement, which includes right to distribute executable
the software license and the files created using the SOFT-
disclaimer of warranty. WARE. You may not, under any
circumstances distribute any
This agreement constitutes the part of the SOFTWARE with your
complete agreement between you executable files.
and GAP Development Company. If
you do not agree to the terms of If you purchased the SOFTWARE
this agreement, promptly return SOURCE CODE, you are granted a
the disks and other items that nonexclusive, personal, non-
are part of this product. transferable, nonassignable li-
cense to use and modify the
The SOFTWARE may not be copied, SOURCE CODE and to distribute
reproduced, disclosed, trans- your programs. You may not re-
ferred, or reduced to any form, produce or distribute the SOURCE
including electronic medium or CODE except in executable form
machine readable form, or trans- as part of your executable file.
mitted or publicly performed by If you distribute your source
any means, electronic or other- code, you may not include the
wise, unless GAP Development SOFTWARE SOURCE CODE as part of
Company consents in writing, in your product.
advance.
This License is effective until
Th SOFTWARE contains valuable terminated. This License will
trade secrets and proprietary terminate automatically if you
information and is protected by fail to comply with any provi-
federal copyright laws. Unautho- sion of this License.
rized use of the software can
result in civil damages and SUMMARY OF LIMITED WARRANTY:
criminal prosecution.
In summary, the SOFTWARE is li-
You may use the SOFTWARE on a censed AS IS. THERE ARE NO
single computer only. You may WARRANTEES, EXPRESS OR IMPLIED,
not network the SOFTWARE or oth- INCLUDING BUT NOT LIMITED TO THE
erwise use it on more than one IMPLIED WARRANTIES OF MER-
computer or terminal at the same CHANTABILITY AND FITNESS FOR A
time. PARTICULAR PURPOSE, AND ALL SUCH
WARRANTIES ARE EXPRESSLY AND
YOU MAY NOT COPY the SOFTWARE SPECIFICALLY DISCLAIMED. IN NO
except to place the programs EVENT SHALL GAP DEVELOPMENT COM-
onto your hard disk and to make PANY BE RESPONSIBLE FOR ANY IN-
archival backup copies onto DIRECT, SPECIAL, INCIDENTAL OR
floppy disks for your personal CONSEQUENTIAL DAMAGES OR LOST
use as permitted by this Li- PROFITS TO YOU OR ANY OTHER PER-
cense. You may not copy the SON OR ENTITY REGARDLESS OF THE
written materials accompanying LEGAL THEORY, EVEN IF WE HAVE
the software. You may not grant BEEN ADVISED OF THE POSSIBILITY
sublicenses nor transfer the OF SUCH DAMAGE.
SOFTWARE or related materials in
any form to any person unless
REGISTRATION INFORMATION
------------------------
GAPQBDR is a user-supported program, also known as
'shareware'. Shareware is a means by which users may 'test-
drive' software before purchasing. Generally, it allows the
user to evaluate the software for a period of 30 days.
After the evaluation period the user must either register
the product or cease using it.
You are permitted under the terms of the above License
Agreement to use GAPQBDR for a period of 30 days without
payment. If you continue to use the product past the 30 day
evaluation period, you must register your copy as described
below.
Commercial use of this software absolutely requires a
registration within the 30 day period. Commercial use
includes any software written by you which utilizes GAPQBDR
and which you charge any sum of money for the use of your
software. This includes shareware registration, donations,
registration fees, or any method you use or devise to
solicit funds from the users of your software.
Commercial use also includes bundling GAPQBDR with other
software even if that other software does not utilize any of
the GAPQBDR functions. This type of commercial use is
strictly prohibited.
A great deal of time, money, and effort went into creating
GAPQBDR. Unlike other libraries of this type, GAPQBDR was
written from scratch and does not have as a basis, "borrowed
code". We have utilized many of the latest features of the
Quick Basic compiler and wrote critical sections in
assembler for speed.
Registration of GAPQBDR is a one time fee of $25.00.
Payment of this fee entitles you to one year of free
upgrades, product support, the right to use GAPQBDR in any
executable program you sell or distribute, a printed manual,
and a good conscience.
Source code is available to registered users for a one time
license fee of $25.00. The source code is fully commented
and well structured.
GAPQBDR Support Board :
The Crow's Nest BBS (714)493-3819 Node 1
(714)493-9851 Node 2
GAPQBDR REGISTRATION
--------------------
Please fill in and detach the following sheet and mail it to
GAP Development Company.
------------------------------------------------------------
I understand and accept the GAPQBDR License Agreement.
Accepted By : ____________________________________
(signature)
Accepted By : ____________________________________
(printed name)
Date : ____________
Product : GAPQBDR
Licensee Information :
Name : ___________________________________________
Address : ___________________________________________
Address : ___________________________________________
City,State,Zip : ___________________________________________
Voice Phone : ________________________
------------------------------------------------------------
# Description Price
------------------------------------------------------------
2001 GAPQBDR Run Time Library 25.00 __________
2002 GAPQBDR Source Code License 25.00 __________
Total Due __________
Less Credit(s) __________
Total Amount Enclosed __________
------------------------------------------------------------
Payment may be made by check or money order
------------------------------------------------------------
GAP Development Company
24242 Porto Fino RT 7715
Laguna Niguel, CA 92677-3844
INDEX
-----
@, 35 BROWN, 12
{, 35 BWHITE, 12
a.ccess%, 23 CYAN, 12
ANSI, 2, 4, 12, 18, 23, 35, 37 GREEN, 12
backspace, 24 MAGENTA, 12
bell, 37 RED, 12
chat, 2, 25, 30, 31, 38, 39, WHITE, 12
40 YELLOW, 12
ckeypress%, 24 General
clear.scr, 24 NO, 12
COMMAND$, 6 YES, 12
communications port, 6 Integers
configuration file, 6 DOOR.SYS
CTS, 2 alarm, 13
CVDMBF, 8, 17, 34 bell, 13
CVSMBF, 8, 17, 34 c.olor, 13
do.chat, 25 expert, 13
do.pcb, 7, 34, 42 l.ocal, 13
DOOR.SYS, 6, 7, 13, 22, 31 level, 13
elap.time, 25 minsleft, 13
Error, 4, 6, 23, 28, 31 node, 13
Files page, 13
Aborting, 36 parity, 13
Color, 35 port, 13
Configuration, 6, 31 printer, 13
DOOR.SYS, 33 s.creen, 13
Errors, 23 GAPDOS
GAPDOS.DAT, 33, 40 gapdos.baud, 14
Include, 4, 6 gapdos.forumnum, 14
Opening, 23 gapdos.givetime, 14
PCB USERS, 34 gapdos.localc, 14
PCBOARD.SYS, 34 gapdos.minavail, 14
Showing, 35 gapdos.port, 14
System, 25, 28 gapdos.timecredit, 15
USERS.DAT, 33, 41 gapdos.userbaud, 15
Functions, 23 General
GAPBBS.CNF, 31 do.pcb, 14
GAPDOS.DAT, 10, 14, 22, 31 noup, 14
get.string, 14, 25, 26, 27, timecredit, 14
30, 38, 41 timeleft, 14
get.time&, 27 PCBSYS
getakey%, 27 pcbsys.minsleft, 16
getrand%, 28 pcbsys.timeallowed, 16
Global Variables pcbsys.timecredit, 16
Constants pcbsys.timegiven, 16
ANSI pcbsys.timeon, 16
BBLACK, 12 pcbsys.timeused, 16
BBLUE, 12 pcbsys.ttlbytes, 16
BCYAN, 12 pcbsys.userrec, 16
BGREEN, 12 PCBUSERS
BLACK, 12 pcbuser.downloads, 16
BLUE, 12 pcbuser.timeson, 17
BMAGENTA, 12 pcbuser.uploads, 17
BRED, 12 USERS
Page 46
INDEX
-----
user.curdown, 15 gapdos.username, 15
user.lastfrm, 15 General
user.level, 15 anystring1, 14
user.minutes, 15 bbs.dir, 14
user.page, 15 board.name, 14
Longs gendir, 14
DOOR.SYS maindir, 14
baud, 13 sysname, 14
downbytes, 13 PCBSYS
downloads, 13 pcbsys.baud, 16
maxbytes, 13 pcbsys.calleralarm, 16
recnum, 13 pcbsys.colorc, 16
timeson, 13 pcbsys.ctime, 16
upbytes, 13 pcbsys.display, 16
uploads, 13 pcbsys.eactive, 16
userbaud, 13 pcbsys.errcorrect, 16
GAPDOS pcbsys.event, 16
gapdos.callbytes, 14 pcbsys.forumnum, 16
gapdos.joined, 14 pcbsys.node, 16
gapdos.starttime, 15 pcbsys.pagebell, 16
General pcbsys.password, 16
starttime, 14 pcbsys.port, 16
temptime, 14 pcbsys.printer, 16
timenow, 14 pcbsys.sevent, 16
USERS pcbsys.sysopnext, 16
user.blts, 15 pcbsys.userbaud, 16
user.curbytes, 15 pcbsys.userfirst, 16
user.doors, 15 pcbsys.username, 16
user.downloads, 15 PCBUSERS
user.joined, 15 pcbuser.bphone, 16
user.lastmsg, 15 pcbuser.city, 16
user.mesleft, 15 pcbuser.cnfregis, 16
user.mesread, 15 pcbuser.delete, 16
user.timeson, 15 pcbuser.downbytes, 16
user.ttlbytes, 15 pcbuser.expert, 16
user.ttlmins, 15 pcbuser.hphone, 16
user.upbytes, 15 pcbuser.lastconf, 16
user.uploads, 15 pcbuser.lastdate, 16
Strings pcbuser.lastdir, 17
DOOR.SYS pcbuser.lastime, 17
bphone, 13 pcbuser.lastmsg, 17
city, 13 pcbuser.lastmsg1, 17
first, 13 pcbuser.level, 17
hphone, 13 pcbuser.name, 17
last, 13 pcbuser.page, 17
lastdate, 13 pcbuser.passwd, 17
password, 13 pcbuser.protocol, 17
subscrip, 13 pcbuser.regisdate, 17
username, 13 pcbuser.upbytes, 17
GAPDOS USERS
gapdos.didnew, 14 user.bphone, 15
gapdos.exitdos, 14 user.city, 15
gapdos.userfirst, 15 user.expert, 15
gapdos.userindex, 15 user.fname, 15
Page 47
INDEX
-----
user.handle, 15 waitasec, 39
user.hphone, 15 wrap.word, 39
user.lastdate, 15 write.gapdos%, 40
user.lastdir, 15 write.gapuser%, 41
user.lasttime, 15 write.pcbsys%, 42
user.lname, 15 write.pcbuser%, 42
user.passwd, 15 write.score, 42
user.private, 15
user.protocol, 15
user.subscribe, 15
user.sysop, 15
IEEE, 8
init.door, 5, 6, 16, 28, 31,
33, 34
leave, 6, 28
mbf, 8
MKDMBF, 42
MKSMBF, 42
more, 29
New Line, 29, 37
nl, 29
no.carrier, 29
node, 6
noup, 26
pagesysop, 30
pause, 30, 39
PCB USERS, 16, 22
PCBOARD.SYS, 6, 7, 16, 22
putachar, 30, 37
putkey, 31, 37
read.cnf, 5, 6, 31
read.doorsys%, 33
read.gapdos%, 33
read.gapuser%, 33
read.pcbsys%, 34
read.pcbuser%, 34
read.score%, 34
right.trim$, 34
set.status, 35
show.file, 35
show.mess, 24, 37, 41
Spaces
Trimming, 34
USERS.DAT, 41
Status Line, 2, 35, 36, 39
string output, 37
Subroutines, 23
time.credit, 38
time.left, 39
timecredit, 38, 40
timeleft, 27
Trimming Spaces, 34
update.clock, 39
USERS.DAT, 10, 15, 22
Page 48
